#!/bin/bash
#
# Automated documentation generator for Pulley
#
# Author:   Dr. Mike Murphy (mmurphy2@coastal.edu)
# Revision: 7 September 2012
#
#   Copyright 2012 Coastal Carolina University
#
#   Licensed under the Apache License, Version 2.0 (the "License");
#   you may not use this file except in compliance with the License.
#   You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#   Unless required by applicable law or agreed to in writing, software
#   distributed under the License is distributed on an "AS IS" BASIS,
#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#   See the License for the specific language governing permissions and
#   limitations under the License.
#


function header() {
   echo "** $1 **"
}

function separator() {
   echo "-------------------------------------------------------------------"
}

function bullet() {
   echo " * $1"
}

function title() {
   echo "==== $1 ===="
}

function summarize() {
   for item in $(ls "$1"); do
      if [ -x "$1/${item}" ]; then
         lhs=$(basename "${item}")
         shorthelp=$("$1/${item}" --shorthelp)
         bullet "${lhs} -- ${shorthelp}"
      fi
   done
}

function detail() {
   for item in $(ls "$1"); do
      if [ -x "$1/${item}" ]; then
         echo ""
         header $(basename "${item}")
         echo ""
         "$1/${item}" --help
         echo ""
         separator
      fi
   done
}

function document() {
   title "$1"
   echo ""
   header "Contents:"
   echo ""
   summarize "$2"
   echo ""
   separator
   detail "$2"
   echo ""
   date=$(date)
   echo -n "== Generated: ${date} =="
}

function show_help() {
   cat << EOF
Component usage: gen_docs [output_path]

Automatically generates Pulley documentation by capturing the --help output
from each agent, command, and component. This component will document both
core scripts, which ship with Pulley, as well as any additional scripts
added by the system administrator or by add-on packages.

Normally, the generated documentation will be placed in the standard Pulley
documentation directory (PULLEY_DOC_DIR) environment variable. However, an
alternate output path may be specified if desired.
EOF
}

function show_summary() {
   echo "Dynamically generates Pulley documentation"
}

ARGS=$(getopt -o "" -l "help,shorthelp" -n "$0" -- "$@")
if [ $? -ne 0 ]; then
   exit 2
fi

eval set -- "$ARGS"

while [ ! "$1" = "--" ]; do
   case "$1" in
      --help)
         shift
         show_help
         exit 0
      ;;
      --shorthelp)
         shift
         show_summary
         exit 0
      ;;
   esac
done

shift

if [ $# -gt 1 ]; then
   echo "Component usage: gen_docs [output_path]" >&2
   exit 2
fi

out_path="${PULLEY_DOC_DIR}"
[ -n "$1" ] && out_path="$1"

# Agent documentation
document "Pulley Agent Documentation" "${PULLEY_AGENT_DIR}" > \
   "${out_path}/agents.txt"
#

# Command documentation
document "Pulley Command Documentation" "${PULLEY_COMMAND_DIR}" > \
   "${out_path}/commands.txt"
#

# Component documentation
document "Pulley Component Documentation" "${PULLEY_COMPONENT_DIR}" > \
   "${out_path}/components.txt"
#

# Python package documentation
rm -rf "${out_path}/packages"
mkdir "${out_path}/packages"
for pkg in $(ls "${PULLEY_PACKAGE_DIR}"); do
   mkdir "${out_path}/packages/${pkg}"
   epydoc --html --graph all --show-imports --show-sourcecode \
       -o "${out_path}/packages/${pkg}" "${PULLEY_PACKAGE_DIR}/${pkg}"
   # Clean up the generated .pyc files
   rm -f "${PULLEY_PACKAGE_DIR}/${pkg}"/*.pyc
done
#
